Inside Macintosh: QuickTime /

Chapter 3 - Image Compression Manager / Image Compression Manager Reference

Image Compression Manager Functions / Working With Sequences

CompressSequenceFrame

Your application calls the CompressSequenceFrame function to compress one of a sequence of frames.

pascal OSErr CompressSequenceFrame (ImageSequence seqID,
                     PixMapHandle src, const Rect *srcRect,
                     CodecFlags flags, Ptr data, long *dataSize,
                     unsigned char *similarity,
                     CompletionProcRecordPtr asyncCompletionProc);

seqID

Unique sequence identifier that was returned by the CompressSequenceBegin function (described in the previous section).

src

Contains a handle to a pixel map that contains the image to be compressed. The image must be stored in a pixel map structure.

srcRect

Contains a pointer to a rectangle defining the portion of the image to compress. The compressor applies this rectangle to the image stored in the buffer referred to by the src parameter.

flags

Specifies flags providing further control information. See "Image Compression Manager Function Control Flags," which begins on page 3-58, for information about CodecFlags fields. You must set the value of either the codecFlagUpdatePrevious flag or the codecFlagUpdatePreviousComp flag to 1 (be sure to set unused flags to 0). The following flags are available for this function:

codecFlagUpdatePrevious

Controls whether the compressor updates the previous image during compression. This flag is only used with sequences that are being temporally compressed. If you set this flag to 1, the compressor copies the current frame into the previous frame buffer at the end of frame compression.

Indicates to the compressor that the image to be compressed has been compressed before. This information may be useful to compressors that can compensate for the image degradation that may otherwise result from repeated compression and decompression of the same image. Set this flag to 1 to indicate that the image was previously compressed. Set this flag to 0 if the image was not previously compressed.

codecFlagUpdatePreviousComp

Controls whether the compressor updates the previous image buffer with the compressed image. This flag is only used with temporal compression and is similar to
the codecFlagUpdatePrevious flag. As with the codecFlagUpdatePrevious flag, if you set this flag to 1, the compressor updates the previous frame buffer at the end of frame compression. However, this flag causes the Image Compression Manager to update the frame buffer using an image obtained by decompressing the results of the most recent compression operation, rather than the source image.

codecFlagForceKeyFrame

Controls whether the compressor creates a key frame from the current image. This flag is only used with temporal compression. If you set this flag to 1, the compressor makes the current image a key frame. If you set this flag to 0, the compressor decides based on other criteria, such as the key frame rate, whether to create a key frame from the current image. If you don't want any key frames other than the ones that are forced, set the key frame rate for the sequence to 0.

codecFlagLiveGrab

Indicates to the compressor that speed is of the
utmost importance, and that size and quality are of lesser importance. This flag is useful when you are grabbing sequences from a live source where each frame must be compressed quickly.

data

Points to a location to receive the compressed image data. It is your program's responsibility to make sure that this location can receive at least as much data as indicated by the GetMaxCompressionSize function (described on page 3-68). The Image Compression Manager places the actual size of the compressed image into the field referred to by the dataSize parameter. This pointer must contain a 32-bit clean address. If you use a dereferenced, locked handle, you must call the Memory Manager's StripAddress routine before you use that pointer with this parameter. For details on StripAddress, see Inside Macintosh: Memory.

dataSize

Contains a pointer to a field that is to receive the size, in bytes, of the compressed image.

similarity

Contains a pointer to a field that is to receive a similarity value. The CompressSequenceFrame function returns a value that indicates the similarity of the current frame to the previous frame. A value of 0 indicates that the current frame is a key frame in the sequence. A value of 255 indicates that the current frame is identical to the previous frame. Values from 1 through 254 indicate relative similarity, ranging from very different (1) to very similar (254).

asyncCompletionProc

Points to a completion function structure. The compressor calls your completion function when an asynchronous compression operation
is complete. You can cause the compression to be performed asynchronously by specifying a completion function if the compressor supports asynchronous compression. For more information about completion function structures, see "Completion Functions" on page 3-148.

If you specify asynchronous operation, you must not read the compressed data until the compressor indicates that the operation is complete by calling your completion function. Set asyncCompletionProc to nil to specify synchronous compression. If you set asyncCompletionProc
to -1, the operation is performed asynchronously but the compressor does not call your completion function.

If the asyncCompletionProc parameter is not nil, the following conditions are in effect: the pixels in the source image must stay valid until the completion function is called with its codecCompletionSource flag, and the resulting compressed data is not valid until it is called with its codecCompletionDest flag set.

SPECIAL CONSIDERATIONS

You must call the CompressSequenceBegin function (described in the previous section) shortly before you use the CompressSequenceFrame function. CompressSequenceFrame uses the current graphics device and port set from your prior call to CompressSequenceBegin.

RESULT CODES

noErr	0	No error
paramErr	-50	Invalid parameter specified
memFullErr	-108	Not enough memory available
noCodecErr	-8961	The Image Compression Manager could not find the specified compressor
codecSpoolErr	-8966	Error loading or unloading data